The Structure Map is a condensed structural view of a selected subset of your code-base. It shows you the selected subset through any Structure Spec that has been saved with the project. In this way it bridges the divide between the architecture and the code you are working on, giving you the insight you need in order to:

• conform to the defined Structure Spec for your project
• understand how dependencies map across your code-base, before and while you make changes
• maintain clean dependency structure
• identify and repair structural problems

Structure Map quick reference

Mouse actions for the Structure Map:

• Pan and Zoom like Google Maps – click/drag to pan; mouse-wheel, 2-finger-up-down, or pinch to zoom
• Click on a composite item (like a package or class) to expand or collapse it
• Cmd/ctrl-click any item to spotlight (i.e. filter the Map for 1 item and it’s dependencies)
• Spotlight a code item (class, field or method) to expose all the item’s code-level dependencies
• Click on a dependency to populate the Dependency Breakout list
• Alt-click an item to go to source editor
• Little dots are shown next to item icons to indicate that they have incomming (top) and/or outgoing dependencies (useful when the dependency itself is not shown)
• Mouse-over items to see all dependencies
• Mouse-over items to see context menu
• Mouse-over tool-bar to see what buttons do

 

Levels tell a story

The items (legend) in the Structure Map are levelized – that is they are arranged into dependency levels so that (as far a possible) all the dependencies flow downward. So items on the bottom level (row) don’t use any other items in the current scope, and items in other levels use at least one item from the level immediately below it.

Where there are cyclic dependencies, strict levelization isn’t possible, but the items are arranged so that as few dependencies as possible flow upward. These are often the “accidental” dependencies (but not necessarily). Non-levelized regions are made clear by a red tangle boxes and feedback dependencies.

Levelization means that you can understand a lot about the dependencies within your code-base without needing to see all the dependencies in your code-base.

Generally only the "interesting" dependencies are shown in the Structure Map (such as spec violations and feedback dependencies). When you mouse-over an item, all the dependencies to and from that item appear.

When an item is spotlit, you know at a glance that (other than tangles) all items above the spotlit item use it, and all items below are used by it.

 

Walking the code-base

If you turn your attention to the Structure Map and wonder for example “what is the spotlight item using inside that class”, simply click on the class and it will expand to show all the dependent methods and fields (any other non-dependent items are not shown). Clicking an expanded item will collapse it again.

You can shift the spotlight in the Structure Map by cmd/ctrl-clicking another item in the Map to cause it to become the new spotlight – the items in the new spotlight’s dependency neighborhood will be added to the view, and the previous spotlight’s dependent items removed (unless they are common to both, in which case you’ll see them shimmy to their new level). This lets you effectively chase dependency threads around your codebase.

At any time you can alt-click an item to navigate from the Structure Map to that item’s code in your source editor (and you can navigate to the Structure Map from source in your editor).

The relevant code-base containers are shown around the spotlight and its neighborhood items – this means you can easily walk the codebase details, in the context of the overall structure/architecture.

Show everything

You can choose to see everything by having nothing spotlit. Well not really everything, just every item that is currently exposed in the Structure Map.

When nothing is spotlit, nothing is filtered.

One way to do this is to explicitly clear the spotlight by cmd/ctrl-clicking the currently spotlit item.

You can also collapse (click) the parent of the spotlit item – this likewise results in a view with no spotlight, so no filtering.

Finally, you can collapse everything and jump straight to the root of your workspace by clicking the "home" button.

The un-spotlit view let’s you use the Structure Map rather than the Project Explorer for navigating your codebase and finding specific items. At that point you might navigate to the code for items (alt-click) or spotlight items (<cmd/ctrl>-click), putting you back into the spotlight view.

Switching between dependency-context and containment-context

By toggling the spotlight on an item (<cmd/ctrl>-click), you effectively switch from seeing the item in the context of its dependencies (wherever they are in your code-base, filtering everything else), to seeing its containment context (exposing its local items, unfiltered).

This is a common workflow – what does this item use?/ what else is in its package?/ what does that item use?/ …

What's new?

If you opt to Show differences, the Structure Map will color code any items and dependencies that are in the code-base, but that were not there previously. A bolder purple indicates that the item or dependency is entirely new. A lighter purple indicates that it is partially new, i.e. a node that is not new, but that includes one or more new items, or a rolled-up dependency that includes one or more new elemental dependencies.

Items are also shown as partly new if they are not themselves new, but a new dependency originates from them.

Newness rolls up through the item containment hierarchy so you can easily drill down to find new items and dependencies.